---
title: 自定义组件
description: Univer 提供了多种方式来集成自定义组件，使您能够扩展和定制 Univer 的功能。本指南将介绍几种常用的方法。
icon: Component
---

Univer 并不会直接将组件作为参数直接传递给任何渲染函数，你需要通过 Facade API 将组件注册到 Univer 中之后，才能在各个挂载点使用它们。

如果你还不了解如何获取 Facade API 的实例，可以参考 [Facade API](/guides/sheets/getting-started/facade)。

<include cwd>content/guides/shared/ui/components.zh-CN.mdx</include>

#### 将弹出框附加到单元格

使用 `FRange.attachPopup` 方法可以将自定义弹出框附加到特定的单元格范围。

- Popup 是一个单元格上面依附的临时 DOM，一般用于显示一些临时的状态信息，不支持持久化存储。
- 使用 [`FRange.attachPopup(popup: IFCanvasPopup)`](https://reference.univer.ai/zh-CN/classes/FRange#attachpopup) 方法可以将自定义弹出框附加到特定的单元格范围。
- Popup 会吸附在单元的四边，如果被遮挡，会自动调整位置和方向。

```tsx
// [!code word:MyCustomPopupComponent]
// 你应该在合适的时机（比如渲染完成）注册组件
univerAPI.registerComponent(
  'MyCustomPopupComponent',
  () => <div>Hello Univer!</div>,
)

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:J10')

// 将弹出窗口附加到范围的第一个单元格
// 如果 `disposable` 为 null，则表示 popup 添加失败
const disposable = fRange.attachPopup({
  componentKey: 'MyCustomPopupComponent',
})

// 移除弹出框
disposable.dispose()
```

#### 附加警告弹出框

使用 `FRange.attachAlertPopup` 方法可以在指定范围的起始单元格附加一个警告弹出框。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')

const disposable = fRange.attachAlertPopup({
  key: 'unique-alert-key', // 唯一标识符
  title: '这是一个警告！',
  message: '这是一个警告！',
  width: 300,
  height: 200,
  // 0: 信息
  // 1: 警告
  // 2: 错误
  type: 0,
})

// 稍后移除警告
disposable.dispose()
```

#### 添加浮动 DOM 到工作表

通过 `FWorksheet.addFloatDomToPosition` 方法可以在工作表上添加一个浮动 DOM。

- 使用该方法前需要安装 `@univerjs/sheets-drawing-ui` 插件或 `@univerjs/preset-sheets-drawing` 预设。
- 浮动 DOM 是悬浮在工作表上的可拖动组件，同时支持持久化存储。
- 需要在 Univer 渲染完成之后调用。
- `componentKey`: 组件的唯一标识符，用于在 Univer 中引用该组件。
- [完整的参数定义](https://github.com/dream-num/univer/blob/dev/packages/sheets-drawing-ui/src/facade/f-worksheet.ts#L32)

```tsx
// [!code word:MyCustomFloatingDOMComponent]
// 你应该在合适的时机（比如渲染完成）注册组件
univerAPI.registerComponent(
  'MyCustomFloatingDOMComponent',
  ({ data }) => (
    <div>
      Hello
      {data?.label}
      !
    </div>
  ),
)
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 添加一个浮动 DOM
// 如果 `disposable` 为 null，则表示浮动 DOM 添加失败
const disposable = fWorksheet.addFloatDomToPosition({
  componentKey: 'MyCustomFloatingDOMComponent',
  initPosition: {
    startX: 100,
    endX: 200,
    startY: 100,
    endY: 200,
  },

  // 这是组件的数据
  data: {
    label: 'Univer',
  },
})

// 移除浮动 DOM
disposable.dispose()
```
